Intro

"나쁜 코드에 주석을 달지 마라. 새로 짜라."
- 브라이언 w. 커니핸, P.J.플라우거 -

코드로 의도를 표현하지 못했을 때, 즉 실패했을 때 우리는 주석을 사용한다.
하지만 주석은 프로그래머들이 유지보수하기는 현실적으로 불가능하다.
따라서 우리는 주석이(간혹 필요할지라도) 필요 없는 방향으로 애너지를 쏟아야 한다.

주석은 나쁜 코드를 보완하지 못한다

표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다. 
자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라!

코드로 의도를 표현하라!

  • 주석으로 의도를 표현한 경우
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if((employee.flags & HOURLY_FLAG) && (employee.age > 65))
  • 코드로 의도를 표현한 경우
if(employee.;isEligibleForFullBenefits())

주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

좋은 주석

1) 법적인 주석

// Copyright (C) ...

2) 정보를 제공하는 주석

// kk:mm:ss EEE, MMM dd, yyyy 형식이다. 
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*")

이왕이면 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 좋고 더 깔끔하겠다.

3) 의도를 설명하는 주석

  • 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명할 수 있다.

4) 의미를 명료하게 밝히는 주석

  • 테스트 코드에서 사용할 수 있다.
assertTrue(a.compareTo(a) == 0);    // a == a

5) 결과를 경고하는 주석

public static SimpleDateFormat makeStanadardHttpDateFormat() {
    // SimpledateFormat은 스레드에 안전하지 못하다.
    // 따라서 각 인스턴스를 독립적으로 생성해야 한다.
}
  • 프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려던 열성적인 프로그래머가 주석 때문에 실수를 면한다.

6) TODO 주석

  • 앞으로 할 일에 대한 주석

7) 중요성을 강조하는 주석

// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.

8) 공개 API에서 Javadocs Javadocs가 없다면 자바 프로그램을 짜기가 아주 어려우리라.

나쁜 주석

1) 주절거리는 주석

2) 같은 이야기를 중복하는 주석

3) 오해할 여지가 있는 주석

4) 의무적으로 다는 주석 모든 함수에 Javadocs를 넣으라는 규칙?

5) 이력을 기록하는 주석

  • 지금은 소스 코드 관리 시스템이 있다.

6) 있으나 마나 한 주석

7) 무서운 잡음

8) 함수나 변수로 표현할 수 있다면 주석을 달지 마라

9) 위치를 표시하는 주석

10) 닫는 괄호에 다는 주석

11) 공로를 돌리거나 저자를 표시하는 주석

  • 요즘 IDE에 기능이 있다.

12) 주석으로 처리한 코드

13) HTML 주석

14) 전역 정보

  • 포트 기본값을 알려준다던지 등등.. 주석을 달아야 한다면 근처에 있는 코드만 기술하자.

15) 너무 많은 정보

16) 모호한 관계

  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
  • 코드만으로 설명이 부족하여 주석을 달았는데, 주석 또한 부족하다면…

17) 함수 헤더

  • 함수 이름을 잘 짓자.

18) 비공개 코드에서 Javadocs

결론

주석을 왜 써야하며, 언제 써야하는지를 알고 쓰는 것이 좋겠다.
좋은 주석을 써야하는 상황과 이유를 아는 것도 좋지만,
나쁜 주석을 인지하고 있는 상태에서 코드와 주석을 단다면
클린 코드로 가는 길이 더 빨라질 것만 같다.